1   /*
2    * Copyright (C) 2007 The Guava Authors
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    * http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package com.google.common.collect;
18  
19  import com.google.common.annotations.GwtCompatible;
20  
21  import java.util.Map;
22  
23  import javax.annotation.Nullable;
24  
25  /**
26   * An object representing the differences between two maps.
27   *
28   * @author Kevin Bourrillion
29   * @since 2.0 (imported from Google Collections Library)
30   */
31  @GwtCompatible
32  public interface MapDifference<K, V> {
33    /**
34     * Returns {@code true} if there are no differences between the two maps;
35     * that is, if the maps are equal.
36     */
37    boolean areEqual();
38  
39    /**
40     * Returns an unmodifiable map containing the entries from the left map whose
41     * keys are not present in the right map.
42     */
43    Map<K, V> entriesOnlyOnLeft();
44  
45    /**
46     * Returns an unmodifiable map containing the entries from the right map whose
47     * keys are not present in the left map.
48     */
49    Map<K, V> entriesOnlyOnRight();
50  
51    /**
52     * Returns an unmodifiable map containing the entries that appear in both
53     * maps; that is, the intersection of the two maps.
54     */
55    Map<K, V> entriesInCommon();
56  
57    /**
58     * Returns an unmodifiable map describing keys that appear in both maps, but
59     * with different values.
60     */
61    Map<K, ValueDifference<V>> entriesDiffering();
62  
63    /**
64     * Compares the specified object with this instance for equality. Returns
65     * {@code true} if the given object is also a {@code MapDifference} and the
66     * values returned by the {@link #entriesOnlyOnLeft()}, {@link
67     * #entriesOnlyOnRight()}, {@link #entriesInCommon()} and {@link
68     * #entriesDiffering()} of the two instances are equal.
69     */
70    @Override
71    boolean equals(@Nullable Object object);
72  
73    /**
74     * Returns the hash code for this instance. This is defined as the hash code
75     * of <pre>   {@code
76     *
77     *   Arrays.asList(entriesOnlyOnLeft(), entriesOnlyOnRight(),
78     *       entriesInCommon(), entriesDiffering())}</pre>
79     */
80    @Override
81    int hashCode();
82  
83    /**
84     * A difference between the mappings from two maps with the same key. The
85     * {@link #leftValue} and {@link #rightValue} are not equal, and one but not
86     * both of them may be null.
87     *
88     * @since 2.0 (imported from Google Collections Library)
89     */
90    interface ValueDifference<V> {
91      /**
92       * Returns the value from the left map (possibly null).
93       */
94      V leftValue();
95  
96      /**
97       * Returns the value from the right map (possibly null).
98       */
99      V rightValue();
100 
101     /**
102      * Two instances are considered equal if their {@link #leftValue()}
103      * values are equal and their {@link #rightValue()} values are also equal.
104      */
105     @Override boolean equals(@Nullable Object other);
106 
107     /**
108      * The hash code equals the value
109      * {@code Arrays.asList(leftValue(), rightValue()).hashCode()}.
110      */
111     @Override int hashCode();
112   }
113 
114 }